package com.pinfly.common.config;

import java.util.Collection;

public abstract interface IPfyProperties
{
    /**
     * Returns the properties for the specified group, using the filepath as the
     * directory to retrieve the properties. The filepath is only used for
     * file-based implementations. In the config server implementation the
     * filepath is ignored.
     * 
     * @param filePath
     * @param groupName
     * @return A CxxProperties instance for the group.
     * @throws ConfigException If any errors were encountered while retrieving
     *             the properties or the properties could not be found.
     * @throws ResourceNotFoundException If the resourceName does not exist or
     *             is not assigned to an hln.
     * @throws IllegalArgumentException If filePath is null or empty
     * @throws IllegalArgumentException If groupName is null or empty
     */
    public PfyProperties getProperties (String filePath, String groupName) throws ConfigException;

    /**
     * Returns the properties for the specified group. If the properties cannot
     * be found using the given arguments an ConfigException is thrown.
     * 
     * @param groupName
     * @return A CxxProperties instance for the group.
     * @throws ConfigException If any errors were encountered while retrieving
     *             the properties or the properties could not be found.
     * @throws ResourceNotFoundException If the resourceName does not exist or
     *             is not assigned to an hln.
     * @throws IllegalArgumentException If groupName is null or empty
     */
    public PfyProperties getProperties (String groupName) throws ConfigException;

    /**
     * Returns a Collection of CxxProperties from the specified list of groups,
     * using the filepath as the directory to retrieve the properties. The
     * filepath is only used for file-based implementations. In the config
     * server implementation the filepath is ignored.
     * 
     * If the properties cannot be found using the given arguments an
     * ConfigException is thrown.
     * 
     * @param filePath
     * @param groupNames
     * @return A Collection of CxxProperties objects.
     * @throws ConfigException If any errors were encountered while retrieving
     *             the properties or the properties could not be found.
     * @throws ResourceNotFoundException If the resourceName does not exist or
     *             is not assigned to an hln.
     * @throws IllegalArgumentException If filePath is null or empty
     * @throws IllegalArgumentException If groupNames is null or empty
     */
    public Collection <PfyProperties> getProperties (String filePath, Collection <String> groupNames)
                                                                                                     throws ConfigException;

    /**
     * Returns a Collection of CxxProperties from the specified list of groups
     * If the properties cannot be found using the given arguments an
     * ConfigException is thrown.
     * 
     * @param groupNames
     * @return A Collection of CxxProperties objects.
     * @throws ConfigException If any errors were encountered while retrieving
     *             the properties or the properties could not be found.
     * @throws ResourceNotFoundException If the resourceName does not exist or
     *             is not assigned to an hln.
     * @throws IllegalArgumentException If groupNames is null or empty
     */
    public Collection <PfyProperties> getProperties (Collection <String> groupNames) throws ConfigException;

    /**
     * Returns a GroupMap object from the specified list of groups, using the
     * filepath as the directory to retrieve the properties. The filepath is
     * only used for file-based implementations. In the config server
     * implementation the filepath is ignored.
     * 
     * If the properties cannot be found using the given arguments an
     * ConfigException is thrown.
     * 
     * The use of a wildcard "*" is supported in the groupNames as long as it
     * isn't the first character and it appears as a suffix. For example "d*"
     * could be used to return CxxProperties for both database and directory
     * groups.
     * 
     * @param filePath
     * @param groupNames
     * @return A GroupMap object.
     * @throws ConfigException If any errors were encountered while retrieving
     *             the properties or the properties could not be found.
     * @throws ResourceNotFoundException If the resourceName does not exist or
     *             is not assigned to an hln.
     * @throws IllegalArgumentException If filePath is null or empty
     * @throws IllegalArgumentException If groupNames is null or empty
     */
    public GroupMap getPropertiesMap (String filePath, Collection <String> groupNames) throws ConfigException;

    /**
     * Returns a GroupMap object from the specified list of groups. If the
     * properties cannot be found using the given arguments an ConfigException
     * is thrown.
     * 
     * The use of a wildcard "*" is supported in the groupNames as long as it
     * isn't the first character and it appears as a suffix. For example "d*"
     * could be used to return CxxProperties for both database and directory
     * groups.
     * 
     * @param groupNames
     * @return A GroupMap object.
     * @throws ConfigException If any errors were encountered while retrieving
     *             the properties or the properties could not be found.
     * @throws ResourceNotFoundException If the resourceName does not exist or
     *             is not assigned to an hln.
     * @throws IllegalArgumentException If groupNames is null or empty
     */
    public GroupMap getPropertiesMap (Collection <String> groupNames) throws ConfigException;

}
